/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.ignite.examples;

import java.net.URL;
import java.util.List;
import org.apache.ignite.Ignite;
import org.apache.ignite.cluster.ClusterGroup;

/**
 * Ignite示例工具类。
 *
 * 这个类提供了所有示例程序中常用的工具方法，包括：
 * - 内存检查：确保JVM有足够的内存运行示例
 * - 资源URL解析：从classpath中查找资源文件
 * - 集群拓扑检查：验证集群中有足够的节点
 * - 服务器节点检查：确保集群中有数据节点
 * - 查询结果格式化：美化SQL查询结果的输出
 *
 * 所有示例都可以使用这个类中的方法来简化代码和确保一致性。
 */
public class ExamplesUtils {
    /** 类加载器，用于从classpath中加载资源文件 */
    private static final ClassLoader CLS_LDR = ExamplesUtils.class.getClassLoader();

    /**
     * 检查JVM最大内存是否满足最小要求。
     *
     * 如果当前JVM的最大可用内存小于指定最小值的85%，程序将退出并返回错误码-1。
     * 这个方法用于确保示例程序有足够的内存正常运行。
     *
     * 为什么是85%而不是100%：因为JVM需要额外的内存用于垃圾回收、
     * 元数据空间等，所以预留一些缓冲空间是合理的。
     *
     * @param min 最小内存阈值（以字节为单位）
     */
    public static void checkMinMemory(long min) {
        long maxMem = Runtime.getRuntime().maxMemory();

        if (maxMem < .85 * min) {
            System.err.println("Heap limit is too low (" + (maxMem / (1024 * 1024)) +
                "MB), please increase heap size at least up to " + (min / (1024 * 1024)) + "MB.");

            System.exit(-1);
        }
    }

    /**
     * 解析并返回示例项目中资源的URL。
     *
     * 这个方法用于从classpath中查找资源文件，特别适用于查找示例项目中的
     * 配置文件、数据文件等资源。如果找不到指定的资源，将抛出运行时异常。
     *
     * 使用场景：
     * - 加载XML配置文件
     * - 读取测试数据文件
     * - 获取属性文件
     *
     * @param path 资源的相对路径（相对于classpath根目录）
     * @return 解析后的资源URL对象
     * @throws RuntimeException 如果找不到指定的资源
     */
    public static URL url(String path) {
        URL url = CLS_LDR.getResource(path);

        if (url == null)
            throw new RuntimeException("Failed to resolve resource URL by path: " + path);

        return url;
    }

    /**
     * 检查集群拓扑大小是否满足运行特定示例的最低要求。
     *
     * 某些示例需要多个节点才能演示分布式特性，例如：
     * - 故障转移示例需要至少2个节点
     * - 数据分区示例需要多个节点来展示数据分布
     * - 服务网格示例需要多个节点来部署服务
     *
     * 如果集群中的节点数量不足，会输出错误信息并返回false。
     *
     * @param grp 要检查的集群组
     * @param size 运行特定示例所需的最小节点数
     * @return 如果检查通过返回true，否则返回false
     */
    public static boolean checkMinTopologySize(ClusterGroup grp, int size) {
        int prjSize = grp.nodes().size();

        if (prjSize < size) {
            System.err.println(">>> Please start at least " + size + " cluster nodes to run example.");

            return false;
        }

        return true;
    }

    /**
     * Checks if cluster has server nodes.
     *
     * @param ignite Ignite instance.
     * @return {@code True} if cluster has server nodes, {@code false} otherwise.
     */
    public static boolean hasServerNodes(Ignite ignite) {
        if (ignite.cluster().forServers().nodes().isEmpty()) {
            System.err.println("Server nodes not found (start data nodes with ExampleNodeStartup class)");

            return false;
        }

        return true;
    }

    /**
     * Convenience method for printing query results.
     *
     * @param res Query results.
     */
    public static void printQueryResults(List<?> res) {
        if (res == null || res.isEmpty())
            System.out.println("Query result set is empty.");
        else {
            for (Object row : res) {
                if (row instanceof List) {
                    System.out.print("(");

                    List<?> l = (List)row;

                    for (int i = 0; i < l.size(); i++) {
                        Object o = l.get(i);

                        if (o instanceof Double || o instanceof Float)
                            System.out.printf("%.2f", o);
                        else
                            System.out.print(l.get(i));

                        if (i + 1 != l.size())
                            System.out.print(',');
                    }

                    System.out.println(')');
                }
                else
                    System.out.println("  " + row);
            }
        }
    }
}
